GraphQL schemos projektavimas: mastelio keitimui pritaikyti modeliai globalioms API

GraphQL tapo galinga alternatyva tradicinėms REST API, suteikdama klientams lankstumo prašyti būtent tų duomenų, kurių jiems reikia. Tačiau, kai jūsų GraphQL API tampa sudėtingesnė ir platesnės apimties – ypač aptarnaujant globalią auditoriją su įvairiais duomenų poreikiais – kruopštus schemos projektavimas tampa gyvybiškai svarbus norint užtikrinti palaikomumą, mastelio keitimą ir našumą. Šiame straipsnyje nagrinėjami keli mastelio keitimui pritaikyti GraphQL schemos projektavimo modeliai, kurie padės jums sukurti tvirtas API, galinčias atlaikyti globalios programos reikalavimus.

Mąstelio keitimui pritaikyto schemos projektavimo svarba

Gerai suprojektuota GraphQL schema yra sėkmingos API pagrindas. Ji nustato, kaip klientai gali sąveikauti su jūsų duomenimis ir paslaugomis. Prastas schemos projektavimas gali sukelti daugybę problemų, įskaitant:

• Našumo problemos: Neefektyvios užklausos ir sprendikliai (resolvers) gali perkrauti jūsų duomenų šaltinius ir sulėtinti atsakymo laiką.
• Priežiūros problemos: Monolitinę schemą tampa sunku suprasti, keisti ir testuoti, kai jūsų programa auga.
• Saugumo spragos: Prastai apibrėžta prieigos kontrolė gali atskleisti jautrius duomenis neautorizuotiems vartotojams.
• Ribotas mastelio keitimas: Glaudžiai susieta schema apsunkina jūsų API paskirstymą tarp kelių serverių ar komandų.

Globalioms programoms šios problemos sustiprėja. Skirtingi regionai gali turėti skirtingus duomenų reikalavimus, reguliavimo apribojimus ir našumo lūkesčius. Mąstelio keitimui pritaikytas schemos projektavimas leidžia efektyviai spręsti šiuos iššūkius.

Pagrindiniai mąstelio keitimui pritaikyto schemos projektavimo principai

Prieš gilinantis į konkrečius modelius, apibrėžkime kelis pagrindinius principus, kuriais turėtumėte vadovautis projektuodami schemą:

• Modularumas: Suskaidykite savo schemą į mažesnius, nepriklausomus modulius. Tai palengvina atskirų API dalių supratimą, keitimą ir pakartotinį naudojimą.
• Komponuojamumas: Projektuokite schemą taip, kad skirtingus modulius būtų galima lengvai derinti ir plėsti. Tai leidžia pridėti naujų funkcijų ir funkcionalumo, netrikdant esamų klientų.
• Abstrakcija: Paslėpkite pagrindinių duomenų šaltinių ir paslaugų sudėtingumą už gerai apibrėžtos GraphQL sąsajos. Tai leidžia keisti įgyvendinimą, nepaveikiant klientų.
• Nuoseklumas: Išlaikykite nuoseklią pavadinimų suteikimo tvarką, duomenų struktūrą ir klaidų apdorojimo strategiją visoje schemoje. Tai palengvina klientams mokytis ir naudotis jūsų API.
• Našumo optimizavimas: Kiekviename schemos projektavimo etape atsižvelkite į našumo pasekmes. Naudokite tokias technikas kaip duomenų įkėlikliai (data loaders) ir laukų pseudonimai (field aliasing), kad sumažintumėte duomenų bazės užklausų ir tinklo užklausų skaičių.

Mąstelio keitimui pritaikyti schemos projektavimo modeliai

Štai keli mąstelio keitimui pritaikyti schemos projektavimo modeliai, kuriuos galite naudoti kurdami tvirtas GraphQL API:

1. Schemų sujungimas (Schema Stitching)

Schemų sujungimas leidžia sujungti kelias GraphQL API į vieną, unifikuotą schemą. Tai ypač naudinga, kai skirtingos komandos ar paslaugos yra atsakingos už skirtingas jūsų duomenų dalis. Tai tarsi turėti kelias mini-API ir sujungti jas per „švyturio“ (gateway) API.

Kaip tai veikia:

1. Kiekviena komanda ar paslauga pateikia savo GraphQL API su savo schema.
2. Centrinė švyturio paslauga naudoja schemų sujungimo įrankius (pvz., Apollo Federation ar GraphQL Mesh), kad sujungtų šias schemas į vieną, unifikuotą schemą.
3. Klientai sąveikauja su švyturio paslauga, kuri nukreipia užklausas į atitinkamas pagrindines API.

Pavyzdys:

Įsivaizduokite e. prekybos platformą su atskiromis API produktams, vartotojams ir užsakymams. Kiekviena API turi savo schemą:

  
    # Produktų API
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # Vartotojų API
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # Užsakymų API
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
    }

    type Query {
      order(id: ID!): Order
    }
  

Švyturio paslauga gali sujungti šias schemas, kad sukurtų unifikuotą schemą:

  
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Order {
      id: ID!
      user: User! @relation(field: "userId")
      product: Product! @relation(field: "productId")
      quantity: Int!
    }

    type Query {
      product(id: ID!): Product
      user(id: ID!): User
      order(id: ID!): Order
    }
  

Atkreipkite dėmesį, kaip Order tipas dabar apima nuorodas į User ir Product, nors šie tipai yra apibrėžti atskirose API. Tai pasiekiama naudojant schemų sujungimo direktyvas (kaip @relation šiame pavyzdyje).

Privalumai:

• Decentralizuota nuosavybė: Kiekviena komanda gali savarankiškai valdyti savo duomenis ir API.
• Pagerintas mastelio keitimas: Galite keisti kiekvienos API mastelį atskirai, atsižvelgiant į jos specifinius poreikius.
• Sumažintas sudėtingumas: Klientams reikia sąveikauti tik su vienu API galiniu tašku.

Svarstytini aspektai:

• Sudėtingumas: Schemų sujungimas gali pridėti sudėtingumo jūsų architektūrai.
• Uždelsimas: Užklausų nukreipimas per švyturio paslaugą gali sukelti uždelsimą.
• Klaidų apdorojimas: Reikia įdiegti tvirtą klaidų apdorojimą, kad būtų galima susidoroti su pagrindinių API gedimais.

2. Schemų federacija (Schema Federation)

Schemų federacija yra schemų sujungimo evoliucija, skirta spręsti kai kuriuos jos apribojimus. Ji suteikia labiau deklaratyvų ir standartizuotą požiūrį į GraphQL schemų komponavimą.

Kaip tai veikia:

1. Kiekviena paslauga pateikia GraphQL API ir anotuoją savo schemą federacijos direktyvomis (pvz., @key, @extends, @external).
2. Centrinė švyturio paslauga (naudojant Apollo Federation) naudoja šias direktyvas, kad sukurtų supergrafą – visos federacinės schemos reprezentaciją.
3. Švyturio paslauga naudoja supergrafą, kad nukreiptų užklausas į atitinkamas pagrindines paslaugas ir išspręstų priklausomybes.

Pavyzdys:

Naudojant tą patį e. prekybos pavyzdį, federacinės schemos galėtų atrodyti taip:

  
    # Produktų API
    type Product @key(fields: "id") {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # Vartotojų API
    type User @key(fields: "id") {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # Užsakymų API
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
      user: User! @requires(fields: "userId")
      product: Product! @requires(fields: "productId")
    }

    extend type Query {
      order(id: ID!): Order
    }
  

Atkreipkite dėmesį į federacijos direktyvų naudojimą:

• @key: Nurodo pirminį tipo raktą.
• @requires: Nurodo, kad laukui reikalingi duomenys iš kitos paslaugos.
• @extends: Leidžia paslaugai išplėsti tipą, apibrėžtą kitoje paslaugoje.

Privalumai:

• Deklaratyvus komponavimas: Federacijos direktyvos palengvina schemų priklausomybių supratimą ir valdymą.
• Pagerintas našumas: Apollo Federation optimizuoja užklausų planavimą ir vykdymą, kad sumažintų uždelsimą.
• Patobulintas tipų saugumas: Supergrafas užtikrina, kad visi tipai būtų nuoseklūs visose paslaugose.

Svarstytini aspektai:

• Įrankiai: Reikia naudoti Apollo Federation arba suderinamą federacijos įgyvendinimą.
• Sudėtingumas: Gali būti sudėtingiau nustatyti nei schemų sujungimą.
• Mokymosi kreivė: Kūrėjai turi išmokti federacijos direktyvas ir koncepcijas.

3. Modulinis schemos projektavimas

Modulinis schemos projektavimas apima didelės, monolitinės schemos suskaidymą į mažesnius, lengviau valdomus modulius. Tai palengvina atskirų API dalių supratimą, keitimą ir pakartotinį naudojimą, net ir nesinaudojant federacinėmis schemomis.

Kaip tai veikia:

1. Nustatykite logines ribas savo schemoje (pvz., vartotojai, produktai, užsakymai).
2. Sukurkite atskirus modulius kiekvienai ribai, apibrėždami su ta riba susijusius tipus, užklausas ir mutacijas.
3. Naudokite importo/eksporto mechanizmus (priklausomai nuo jūsų GraphQL serverio įgyvendinimo), kad sujungtumėte modulius į vieną, unifikuotą schemą.

Pavyzdys (naudojant JavaScript/Node.js):

Sukurkite atskirus failus kiekvienam moduliui:

  
    // vartotojai.graphql
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    // produktai.graphql
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }
  

Tada sujunkite juos pagrindiniame schemos faile:

  
    // schema.js
    const { makeExecutableSchema } = require('graphql-tools');
    const { typeDefs: userTypeDefs, resolvers: userResolvers } = require('./users');
    const { typeDefs: productTypeDefs, resolvers: productResolvers } = require('./products');

    const typeDefs = [
      userTypeDefs,
      productTypeDefs,
      ""
    ];

    const resolvers = {
      Query: {
        ...userResolvers.Query,
        ...productResolvers.Query,
      }
    };

    const schema = makeExecutableSchema({
      typeDefs,
      resolvers,
    });

    module.exports = schema;
  

Privalumai:

• Pagerintas palaikomumas: Mažesnius modulius lengviau suprasti ir keisti.
• Padidintas pakartotinis naudojimas: Modulius galima pakartotinai naudoti kitose jūsų programos dalyse.
• Geresnis bendradarbiavimas: Skirtingos komandos gali dirbti su skirtingais moduliais savarankiškai.

Svarstytini aspektai:

• Pridėtinės išlaidos: Modularizacija gali pridėti šiek tiek pridėtinių išlaidų jūsų kūrimo procesui.
• Sudėtingumas: Reikia atidžiai apibrėžti ribas tarp modulių, kad būtų išvengta ciklinių priklausomybių.
• Įrankiai: Reikia naudoti GraphQL serverio įgyvendinimą, kuris palaiko modulinį schemos apibrėžimą.

4. Sąsajų ir junginių tipai

Sąsajų (Interface) ir junginių (Union) tipai leidžia apibrėžti abstrakčius tipus, kuriuos gali įgyvendinti keli konkretūs tipai. Tai naudinga reprezentuojant polimorfinius duomenis – duomenis, kurie gali įgyti skirtingas formas priklausomai nuo konteksto.

Kaip tai veikia:

• Apibrėžkite sąsają ar junginio tipą su bendrų laukų rinkiniu.
• Apibrėžkite konkrečius tipus, kurie įgyvendina sąsają arba yra junginio nariai.
• Naudokite lauką __typename, kad identifikuotumėte konkretų tipą vykdymo metu.

Pavyzdys:

  
    interface Node {
      id: ID!
    }

    type User implements Node {
      id: ID!
      name: String!
      email: String!
    }

    type Product implements Node {
      id: ID!
      name: String!
      price: Float!
    }

    union SearchResult = User | Product

    type Query {
      node(id: ID!): Node
      search(query: String!): [SearchResult!]!
    }
  

Šiame pavyzdyje tiek User, tiek Product įgyvendina Node sąsają, kuri apibrėžia bendrą id lauką. SearchResult junginio tipas reprezentuoja paieškos rezultatą, kuris gali būti arba User, arba Product. Klientai gali siųsti užklausą į `search` lauką ir tada naudoti `__typename` lauką, kad nustatytų, kokio tipo rezultatą jie gavo.

Privalumai:

• Lankstumas: Leidžia saugiai reprezentuoti polimorfinius duomenis.
• Kodo pakartotinis naudojimas: Sumažina kodo dubliavimą, apibrėžiant bendrus laukus sąsajose ir junginiuose.
• Pagerintas užklausų pateikimas: Palengvina klientams užklausų pateikimą dėl skirtingų tipų duomenų naudojant vieną užklausą.

Svarstytini aspektai:

• Sudėtingumas: Gali pridėti sudėtingumo jūsų schemai.
• Našumas: Sąsajų ir junginių tipų sprendimas gali būti brangesnis nei konkrečių tipų sprendimas.
• Introspekcija: Reikalauja, kad klientai naudotų introspekciją, norėdami nustatyti konkretų tipą vykdymo metu.

5. Ryšio modelis (Connection Pattern)

Ryšio modelis yra standartinis būdas įgyvendinti puslapiavimą GraphQL API. Jis suteikia nuoseklų ir efektyvų būdą gauti didelius duomenų sąrašus dalimis.

Kaip tai veikia:

• Apibrėžkite ryšio tipą su edges ir pageInfo laukais.
• edges lauke yra briaunų sąrašas, kurių kiekviena turi node lauką (faktinius duomenis) ir cursor lauką (unikalų mazgo identifikatorių).
• pageInfo lauke yra informacija apie dabartinį puslapį, pavyzdžiui, ar yra daugiau puslapių ir pirmo bei paskutinio mazgų kursoriai.
• Naudokite first, after, last ir before argumentus, kad valdytumėte puslapiavimą.

Pavyzdys:

  
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type UserEdge {
      node: User!
      cursor: String!
    }

    type UserConnection {
      edges: [UserEdge!]!
      pageInfo: PageInfo!
    }

    type PageInfo {
      hasNextPage: Boolean!
      hasPreviousPage: Boolean!
      startCursor: String
      endCursor: String
    }

    type Query {
      users(first: Int, after: String, last: Int, before: String): UserConnection!
    }
  

Privalumai:

• Standartizuotas puslapiavimas: Suteikia nuoseklų būdą įgyvendinti puslapiavimą visoje jūsų API.
• Efektyvus duomenų gavimas: Leidžia gauti didelius duomenų sąrašus dalimis, sumažinant serverio apkrovą ir gerinant našumą.
• Kursoriais pagrįstas puslapiavimas: Naudoja kursorius kiekvieno mazgo pozicijai sekti, o tai yra efektyviau nei poslinkiu pagrįstas puslapiavimas.

Svarstytini aspektai:

• Sudėtingumas: Gali pridėti sudėtingumo jūsų schemai.
• Pridėtinės išlaidos: Reikalauja papildomų laukų ir tipų, kad būtų galima įgyvendinti ryšio modelį.
• Įgyvendinimas: Reikalauja kruopštaus įgyvendinimo, siekiant užtikrinti, kad kursoriai būtų unikalūs ir nuoseklūs.

Globalūs aspektai

Projektuojant GraphQL schemą globaliai auditorijai, atsižvelkite į šiuos papildomus veiksnius:

• Lokalizacija: Naudokite direktyvas arba pasirinktinius skaliarinius tipus, kad palaikytumėte skirtingas kalbas ir regionus. Pavyzdžiui, galėtumėte turėti pasirinktinį `LocalizedText` skaliarą, kuris saugo vertimus skirtingoms kalboms.
• Laiko juostos: Laiko žymes saugokite UTC formatu ir leiskite klientams nurodyti savo laiko juostą rodymo tikslais.
• Valiutos: Naudokite nuoseklų valiutos formatą ir leiskite klientams nurodyti pageidaujamą valiutą rodymo tikslais. Apsvarstykite galimybę naudoti pasirinktinį `Currency` skaliarą tam reprezentuoti.
• Duomenų rezidencija: Užtikrinkite, kad jūsų duomenys būtų saugomi laikantis vietinių teisės aktų. Tam gali prireikti diegti jūsų API keliuose regionuose arba naudoti duomenų maskavimo technikas.
• Prieinamumas: Projektuokite schemą taip, kad ji būtų prieinama vartotojams su negalia. Naudokite aiškius ir aprašomuosius laukų pavadinimus ir pateikite alternatyvius būdus prieiti prie duomenų.

Pavyzdžiui, apsvarstykite produkto aprašymo lauką:

type Product {
 id: ID!
 name: String!
 description(language: String = "en"): String!
}

Tai leidžia klientams prašyti aprašymo konkrečia kalba. Jei kalba nenurodyta, numatytoji yra anglų (`en`).

Išvados

Mąstelio keitimui pritaikytas schemos projektavimas yra būtinas norint sukurti tvirtas ir lengvai prižiūrimas GraphQL API, galinčias atlaikyti globalios programos reikalavimus. Laikydamiesi šiame straipsnyje aprašytų principų ir naudodami tinkamus projektavimo modelius, galite sukurti API, kurias lengva suprasti, keisti ir plėsti, kartu užtikrinant puikų našumą ir mastelio keitimą. Nepamirškite modularizuoti, komponuoti ir abstrahuoti savo schemą bei atsižvelgti į specifinius jūsų globalios auditorijos poreikius.

Taikydami šiuos modelius, galite atskleisti visą GraphQL potencialą ir sukurti API, kurios maitins jūsų programas ateinančius metus.